home *** CD-ROM | disk | FTP | other *** search
/ PCGUIA 114 / PC Guia 114.iso / Software / Utils / The Gimp 2.2.1 / gimp-help-2-0.6-setup.exe / {app} / share / gimp / 2.0 / help / en / ch02s10s04.html < prev    next >
Encoding:
Extensible Markup Language  |  2004-12-19  |  17.0 KB  |  453 lines
  1. <?xml version="1.0" encoding="UTF-8" standalone="no"?>
  2. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  3. <html xmlns="http://www.w3.org/1999/xhtml">
  4.   <head>
  5.     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  6.     <title>10.4.┬áYour First Script-Fu Script</title>
  7.     <link rel="stylesheet" href="gimp-help-plain.css" type="text/css" />
  8.     <link rel="stylesheet" href="gimp-help-screen.css" type="text/css" />
  9.     <meta name="generator" content="DocBook XSL Stylesheets V1.66.1" />
  10.     <link rel="start" href="index.html" title="GIMP User Manual" />
  11.     <link rel="up" href="ch02s10.html" title="10.┬áA Script-Fu Tutorial" />
  12.     <link rel="prev" href="ch02s10s03.html" title="10.3.┬áLists, Lists And More Lists" />
  13.     <link rel="next" href="ch02s10s05.html" title="10.5.┬áGiving Our Script Some Guts" />
  14.   </head>
  15.   <body>
  16.     <div xmlns="" class="navheader">
  17.       <table width="100%" summary="Navigation header">
  18.         <tr>
  19.           <th colspan="3" align="center" id="chaptername">10.┬áA Script-Fu Tutorial</th>
  20.         </tr>
  21.         <tr>
  22.           <td width="20%" align="left"><a accesskey="p" href="ch02s10s03.html">Prev</a>┬á</td>
  23.           <th width="60%" align="center" id="sectionname">10.4.┬áYour First Script-Fu Script</th>
  24.           <td width="20%" align="right">┬á<a accesskey="n" href="ch02s10s05.html">Next</a></td>
  25.         </tr>
  26.       </table>
  27.       <hr />
  28.     </div>
  29.     <div class="sect2" lang="en" xml:lang="en">
  30.       <div class="titlepage">
  31.         <div>
  32.           <div>
  33.             <h3 class="title"><a id="id3430165"></a>10.4.┬áYour First Script-Fu Script</h3>
  34.           </div>
  35.         </div>
  36.       </div>
  37.       <p>
  38.       Do you not need to stop and catch your breath? No? Well then,
  39.       let's proceed with your fourth lesson -- your first Script-Fu
  40.       Script. 
  41.     </p>
  42.       <div class="simplesect" lang="en" xml:lang="en">
  43.         <div class="titlepage">
  44.           <div>
  45.             <div>
  46.               <h4 class="title"><a id="id3430179"></a>Creating A Text Box Script</h4>
  47.             </div>
  48.           </div>
  49.         </div>
  50.         <p>
  51.         One of the most common operations I perform in Gimp is
  52.         creating a box with some text in it for a web page, a logo or
  53.         whatever. However, you never quite know how big to make the
  54.         initial image when you start out. You don't know how much
  55.         space the text will fill with the font and font size you
  56.         want. 
  57.       </p>
  58.         <p>
  59.         The Script-Fu Master (and student) will quickly realize that
  60.         this problem can easily be solved and automated with
  61.         Script-Fu. 
  62.       </p>
  63.         <p>
  64.         We will, therefore, create a script, called Text Box, which
  65.         creates an image correctly sized to fit snugly around a line
  66.         of text the user inputs. We'll also let the user choose the
  67.         font, font size and text color. 
  68.       </p>
  69.       </div>
  70.       <div class="simplesect" lang="en" xml:lang="en">
  71.         <div class="titlepage">
  72.           <div>
  73.             <div>
  74.               <h4 class="title"><a id="id3430209"></a>Editing And Storing Your Scripts</h4>
  75.             </div>
  76.           </div>
  77.         </div>
  78.         <p>
  79.         Up until now, we've been working in the Script-Fu
  80.         Console. Now, however, we're going to switch to editing script
  81.         text files. 
  82.       </p>
  83.         <p>
  84.         Where you place your scripts is a matter of preference -- if
  85.         you have access to Gimp's default script directory, you can
  86.         place your scripts there. However, I prefer keeping my
  87.         personal scripts in my own script directory, to keep them
  88.         separate from the factory-installed scripts. 
  89.       </p>
  90.         <p>
  91.         In the <tt class="filename">.gimp-2.0</tt> directory that Gimp made
  92.         off of your home directory, you should find a directory called
  93.         <tt class="filename">scripts</tt>. Gimp will automatically look in
  94.         your <tt class="filename">.gimp-2.0</tt> directory for a scripts
  95.         directory, and add the 
  96.         scripts in this directory to the Script-Fu database. You
  97.         should place your personal scripts here. 
  98.       </p>
  99.       </div>
  100.       <div class="simplesect" lang="en" xml:lang="en">
  101.         <div class="titlepage">
  102.           <div>
  103.             <div>
  104.               <h4 class="title"><a id="id3430259"></a>The Bare Essentials</h4>
  105.             </div>
  106.           </div>
  107.         </div>
  108.         <p>
  109.         Every Script-Fu script defines at least one function, which is
  110.         the script's main function. This is where you do the work. 
  111.       </p>
  112.         <p>
  113.         Every script must also register with the procedural database,
  114.         so you can access it within Gimp. 
  115.       </p>
  116.         <p>
  117.        We'll define the main function first:
  118.       </p>
  119.         <pre class="programlisting">
  120.         (define (script-fu-text-box inText inFont inFontSize inTextColor))
  121.       </pre>
  122.         <p>
  123.         Here, we've defined a new function called script-fu-text-box
  124.         that takes four parameters, which will later correspond to
  125.         some text, a font, the font size, and the text's color. The
  126.         function is currently empty and thus does nothing. So far, so
  127.         good -- nothing new, nothing fancy. 
  128.       </p>
  129.       </div>
  130.       <div class="simplesect" lang="en" xml:lang="en">
  131.         <div class="titlepage">
  132.           <div>
  133.             <div>
  134.               <h4 class="title"><a id="id3430296"></a>Naming Conventions</h4>
  135.             </div>
  136.           </div>
  137.         </div>
  138.         <p>
  139.         Scheme's naming conventions seem to prefer lowercase letters
  140.         with hyphens, which I've followed in the naming of the
  141.         function. However, I've departed from the convention with the
  142.         parameters. I like more descriptive names for my parameters
  143.         and variables, and thus add the "in" prefix to the parameters
  144.         so I can quickly see that they're values passed into the
  145.         script, rather than created within it. I use the prefix "the"
  146.         for variables defined within the script. 
  147.       </p>
  148.         <p>
  149.         It's Gimp convention to name your script functions
  150.         script-fu-abc, because then when they're listed in the
  151.         procedural database, they'll all show up under script-fu when
  152.         you're listing the functions. This also helps distinguish them
  153.         from plug-ins. 
  154.       </p>
  155.       </div>
  156.       <div class="simplesect" lang="en" xml:lang="en">
  157.         <div class="titlepage">
  158.           <div>
  159.             <div>
  160.               <h4 class="title"><a id="id3430324"></a>Registering The Function</h4>
  161.             </div>
  162.           </div>
  163.         </div>
  164.         <p>
  165.         Now, let's register the function with Gimp. This is done by
  166.         calling the function <tt class="code">script-fu-register</tt>. When
  167.         Gimp reads in a 
  168.         script, it will execute this function, which registers the
  169.         script with the procedural database. You can place this
  170.         function call wherever you wish in your script, but I usually
  171.         place it at the end, after all my other code. 
  172.       </p>
  173.         <p>
  174.         Here's the listing for registering this function (I will
  175.         explain all its parameters in a minute): 
  176.       </p>
  177.         <pre class="programlisting">
  178.  
  179.         (script-fu-register
  180.           "script-fu-text-box"                      ;func name
  181.           "<Toolbox>/Xtns/Script-Fu/Text/Text Box"  ;menu pos  
  182.           "Creates a simple text box, sized to fit\
  183.             around the user's choice of text,\
  184.             font, font size, and color."            ;description
  185.           "Michael Terry"                           ;author
  186.           "copyright 1997, Michael Terry"           ;copyright notice
  187.           "October 27, 1997"                        ;date created
  188.           ""                  ;image type that the script works on
  189.           SF-VALUE "Text:"       "\"Text Box\""     ;a text variable
  190.           SF-VALUE "Font:"       "\"Charter\""      ;a text variable
  191.           SF-VALUE "Font size:"     "45"               ;a text variable
  192.           SF-COLOR "Color:"      '(0 0 0)           ;color variable
  193.         )
  194.  
  195.       </pre>
  196.         <p>
  197.         If you save these functions in a text file with a
  198.         <tt class="filename">.scm</tt> suffix
  199.         in your script directory, then choose
  200.         <span class="guimenu">Xtns</span>-><span class="guisubmenu">Script-Fu</span>-><span class="guimenuitem">Refresh</span>,
  201.         this new script will appear as
  202.         <span class="guimenu"> Xtns</span>-><span class="guisubmenu">Script-Fu</span>-><span class="guisubmenu">Text</span>-><span class="guimenuitem">Text Box</span>. 
  203.       </p>
  204.         <p>
  205.         If you invoke this new script, it won't do anything, of
  206.         course, but you can view the prompts you created when
  207.         registering the script (more information about what we did is
  208.         covered next). 
  209.       </p>
  210.         <p>
  211.         Finally, if you invoke the DB Browser (the procedural database
  212.         browser -- 
  213.         <span class="guimenu"> Xtns</span>-><span class="guimenuitem">DB Browser</span>), 
  214.         you'll notice that our script now
  215.         appears in the database. 
  216.       </p>
  217.       </div>
  218.       <div class="simplesect" lang="en" xml:lang="en">
  219.         <div class="titlepage">
  220.           <div>
  221.             <div>
  222.               <h4 class="title"><a id="id3430457"></a>Steps For Registering The Script</h4>
  223.             </div>
  224.           </div>
  225.         </div>
  226.         <p>
  227.         To register our script with Gimp, we call the function
  228.         script-fu-register, fill in the seven required parameters and
  229.         add our script's own parameters, along with a description and
  230.         default value for each parameter.
  231.       </p>
  232.         <div class="itemizedlist">
  233.           <p class="title">
  234.             <b>The Required Parameters</b>
  235.           </p>
  236.           <ul type="disc">
  237.             <li>
  238.               <p>
  239.           The <span class="bold"><b>name</b></span> of the function we
  240.           defined. This is the function 
  241.           called when our script is invoked (the entry-point into our
  242.           script). This is necessary because we may define additional
  243.           functions within the same file, and Gimp needs to know which
  244.           of these functions to call. In our example, we only defined
  245.           one function, text-box, which we registered. 
  246.         </p>
  247.             </li>
  248.             <li>
  249.               <p>
  250.           The <span class="bold"><b>location</b></span> in the menu
  251.           where the script will be 
  252.           inserted. The exact location of the script is specified like a
  253.           path in Unix, with the root of the path being either toolbox
  254.           or right-click. 
  255.         </p>
  256.             </li>
  257.             <li>
  258.               <p>
  259.             If your script does not operate on an existing image (and
  260.             thus creates a new image, like our Text Box script will),
  261.             you'll want to insert it in the toolbox menu -- this is the
  262.             menu in Gimp's main window (where all the tools are located:
  263.             the selection tools, magnifying glass, etc.). 
  264.           </p>
  265.               <p>
  266.             If your script is intended to work on an image being edited,
  267.             you'll want to insert it in the menu that appears when you
  268.             right-click on an open image. The rest of the path points to
  269.             the menu lists, menus and sub-menus. Thus, we registered our
  270.             Text Box script in the Text menu of the Script-Fu menu of
  271.             the Xtns menu of the toolbox (
  272.             <span class="guimenu"> Xtns</span>-><span class="guisubmenu">Script-Fu</span>-><span class="guisubmenu">Text</span>-><span class="guimenuitem">Text Box</span> 
  273.             ). 
  274.           </p>
  275.               <p>
  276.             If you notice, the Text sub-menu in the Script-Fu menu
  277.             wasn't there when we began -- Gimp automatically creates any
  278.             menus not already existing. 
  279.         </p>
  280.             </li>
  281.             <li>
  282.               <p>
  283.           A <span class="bold"><b>description</b></span> of your
  284.           script, to be displayed in the DB Browser.
  285.         </p>
  286.             </li>
  287.             <li>
  288.               <p>
  289.           <span class="bold"><b>Your name</b></span> (the author of
  290.           the script). 
  291.         </p>
  292.             </li>
  293.             <li>
  294.               <p>
  295.           <span class="bold"><b>Copyright</b></span> information.
  296.         </p>
  297.             </li>
  298.             <li>
  299.               <p>
  300.            The <span class="bold"><b>date</b></span> the script was
  301.            made, or the last revision of the script. 
  302.         </p>
  303.             </li>
  304.             <li>
  305.               <p>
  306.           The <span class="bold"><b>types</b></span> of images the
  307.           script works on. This may be any of the following: RGB,
  308.           RGBA, GRAY, GRAYA, INDEXED, INDEXEDA. Or it may be none at
  309.           all -- in our case, we're creating an image, and thus don't
  310.           need to define the type of image on which we work. 
  311.         </p>
  312.             </li>
  313.           </ul>
  314.         </div>
  315.       </div>
  316.       <div class="simplesect" lang="en" xml:lang="en">
  317.         <div class="titlepage">
  318.           <div>
  319.             <div>
  320.               <h4 class="title"><a id="id3430624"></a>Registering The Script's Parameters</h4>
  321.             </div>
  322.           </div>
  323.         </div>
  324.         <p>
  325.         Once we have listed the required parameters, we then need to
  326.         list the parameters that correspond to the parameters our
  327.         script needs. When we list these params, we give hints as to
  328.         what their types are. This is for the dialog which pops up
  329.         when the user selects our script. We also provide a default
  330.         value. 
  331.       </p>
  332.         <p>
  333.         This section of the registration process has the following format:
  334.       </p>
  335.         <div class="informaltable">
  336.           <table border="1">
  337.             <colgroup>
  338.               <col />
  339.               <col />
  340.               <col />
  341.             </colgroup>
  342.             <thead>
  343.               <tr>
  344.                 <th>
  345.                   <p>Param Type</p>
  346.                 </th>
  347.                 <th>
  348.                   <p>Description</p>
  349.                 </th>
  350.                 <th>
  351.                   <p>Example</p>
  352.                 </th>
  353.               </tr>
  354.             </thead>
  355.             <tbody>
  356.               <tr>
  357.                 <td>
  358.                   <p>SF-VALUE</p>
  359.                 </td>
  360.                 <td>
  361.                   <p>
  362.               Accepts numbers and strings. Note that quotes must be
  363.               escaped for default text. 
  364.             </p>
  365.                 </td>
  366.                 <td>
  367.                   <p>"\"Some text\""</p>
  368.                 </td>
  369.               </tr>
  370.               <tr>
  371.                 <td>
  372.                   <p>SF-COLOR</p>
  373.                 </td>
  374.                 <td>
  375.                   <p>
  376.               Indicates that a color is requested in this parameter
  377.             </p>
  378.                 </td>
  379.                 <td>
  380.                   <p>'(0 102 255)</p>
  381.                 </td>
  382.               </tr>
  383.               <tr>
  384.                 <td>
  385.                   <p>SF-TOGGLE</p>
  386.                 </td>
  387.                 <td>
  388.                   <p>
  389.               A checkbox is displayed, to get a Boolean value.
  390.             </p>
  391.                 </td>
  392.                 <td>
  393.                   <p>TRUE or FALSE</p>
  394.                 </td>
  395.               </tr>
  396.               <tr>
  397.                 <td>
  398.                   <p>SF-IMAGE</p>
  399.                 </td>
  400.                 <td>
  401.                   <p>
  402.               If your script operates on an open image, this should be
  403.               the first parameter after the required parameters. Gimp
  404.               will pass in a reference to the image in this parameter. 
  405.             </p>
  406.                 </td>
  407.                 <td>
  408.                   <p>3</p>
  409.                 </td>
  410.               </tr>
  411.               <tr>
  412.                 <td>
  413.                   <p>SF-DRAWABLE</p>
  414.                 </td>
  415.                 <td>
  416.                   <p>
  417.               If your script operates on an open image, this should be
  418.               the second parameter after the SF-IMAGE param. It refers
  419.               to the active layer. Gimp will pass in a reference to the
  420.               active layer in this parameter. 
  421.             </p>
  422.                 </td>
  423.                 <td>
  424.                   <p>17</p>
  425.                 </td>
  426.               </tr>
  427.             </tbody>
  428.           </table>
  429.         </div>
  430.       </div>
  431.     </div>
  432.     <div class="navfooter">
  433.       <hr />
  434.       <table width="100%" summary="Navigation footer">
  435.         <tr>
  436.           <td width="40%" align="left"><a accesskey="p" href="ch02s10s03.html">Prev</a>┬á</td>
  437.           <td width="20%" align="center">
  438.             <a accesskey="u" href="ch02s10.html">Up</a>
  439.           </td>
  440.           <td width="40%" align="right">┬á<a accesskey="n" href="ch02s10s05.html">Next</a></td>
  441.         </tr>
  442.         <tr>
  443.           <td width="40%" align="left" valign="top">10.3.┬áLists, Lists And More Lists┬á</td>
  444.           <td width="20%" align="center">
  445.             <a accesskey="h" href="index.html">Home</a>
  446.           </td>
  447.           <td width="40%" align="right" valign="top">┬á10.5.┬áGiving Our Script Some Guts</td>
  448.         </tr>
  449.       </table>
  450.     </div>
  451.   </body>
  452. </html>
  453.